/*
 *    @(#) 2.4 src/somples.os2/somd/c/proxy/readme, somx, som2.0.fix, csd2.0.4 4/21/94 16:21:41 [5/23/94 10:11:02]
 */

/*
 * 96F8647, 96F8648, 96F8850 (C) Copyright IBM Corp. 1992, 1994
 * All Rights Reserved
 * Licensed Materials - Property of IBM
 *
 * DISCLAIMER OF WARRANTIES.
 * The following [enclosed] code is sample code created by IBM
 * Corporation. This sample code is not part of any standard or IBM
 * product and is provided to you solely for the purpose of assisting
 * you in the development of your applications.  The code is provided
 * "AS IS". IBM MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
 * NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE, REGARDING THE FUNCTION OR PERFORMANCE OF
 * THIS CODE.  IBM shall not be liable for any damages arising out of
 * your use of the sample code, even if they have been advised of the
 * possibility of such damages.
 *
 * DISTRIBUTION.
 * This sample code can be freely distributed, copied, altered, and
 * incorporated into other software, provided that it bears the above
 * Copyright notice and DISCLAIMER intact.
 */


This directory contains a simple example of how to write a
user-supplied proxy object. In this particular example, the proxy
object maintains a local, unshared copy of the attribute
(attribute_long) defined in the remote object (Bar) while forwarding
the method call (_method1) to the remote object. The result is that
when multiple clients are talking to the same remote Bar object, each
client has a local copy of the attribute but all clients share the Bar
object's implementation of _method1. Setting the attribute in one
client's proxy does not affect the value of the attribute in other
proxies.

The user-supplied proxy was created by using multiple inheritance between
SOMDClientProxy and the target object (in this case Bar). The idl and
implementation files for Bar are in bar.idl and bar.c respectively.
The idl file for SOMDClientProxy is in %SOMBASE%\include.  The idl and
implementation files for the proxy are in barproxy.idl and barproxy.c
respectively.

When a dynamic proxy is created by the DSOM runtime, the methods
inherited from the target class are overridden to send the method call
remotely instead of to the local object. When one builds a user-defined
proxy, one needs to do this explicitly.  This is why method1 is
overridden in the implementation section of the barproxy.idl file.

In barproxy.c the implementation of method1 simply calls the somDispatch
method on itself. This is because SOMDClientProxy overrides the default
SOM somDispatch method to send the method remotely. Because Barproxy
has inherited this implementation, calling somDispatch within method1
sends the method to the remote Bar object.

This sample is described in the SOMobjects Developer Toolkit Users Guide
under the section "Creating user-supplied proxies".  However, this sample
has changed class Foo to Bar and class Foo__Proxy to Bar__Proxy.  This name
change was made to avoid class name conflicts with the sample in the "dii"
subdirectory.

NOTE:  Please review the README in %SOMBASE%\samples\somd for general
       information on setting up and running DSOM samples.  This
       README assumes that information.

BUILDING THE SAMPLE
-------------------

The makefile in this directory will build the client executable and
the dynamically loadable library. They are:

- tstproxy (the DSOM client program)

- proxy.dll (DLL containing the Bar and Bar__Proxy classes used by the
             server and the DSOM runtime)

Note that for simplicity the Bar and Bar__Proxy classes have been bundled
in the same dll.  Usually, each would be in a separate dll.  To determine
whether a user-supplied proxy class exists, the DSOM runtime checks the
LIBPATH for a DLL containing the class named "<targetClassName>__Proxy".
If it is found, it is loaded instead of dynamically generating a proxy 
class.

RUNNING THE SAMPLE
------------------

Remember that the DSOM daemon "somdd", must be started before
executing the sample.

Start two or more copies of tstproxy in separate windows.

When the first instance of tstproxy is executed it creates the remote
object Bar in the server and writes the string form of its object
reference in a file called: fileref. The next instance of tstproxy
started finds the reference in fileref and creates a proxy to connect
to the (previously created) Bar object. 

After terminating all the instances of tstproxy, somdd and somdsvr,
be sure to remove fileref - otherwise the next time tstproxy is
executed, it will try to connect to the object whose reference is in
fileref - which may no longer exist.
